home *** CD-ROM | disk | FTP | other *** search
/ Beginning Mac Programming / Beginning Mac Programming.bin / Open Me for REALbasic 3 / REALbasic 3.2 / Example Projects / Techniques / Examples by Thomas Tempelmann / TT's AliasRecord / TT's Alias Mgr Plugin - ReadMe
Text File  |  1999-07-05  |  8KB  |  161 lines
  1. TT's Alias Mgr Plugin for REALbasic
  2.  
  3. General Information
  4.  
  5. By Thomas Tempelmann
  6. Current version: 1.1 (July 5, 1999)
  7.  
  8. This is freeware. Use it as you like.
  9. (And if you have created some nice things, think about sharing them, too!)
  10.  
  11. This is a Plugin for REALbasic version 2 or later (it does not work with REALbasic v1!). Plugins contain usually low-level code that cannot be written using the REALbasic language directly.
  12.  
  13. The plugin and the sample RB program were created and tested using CodeWarrior Pro 3 and REALbasic 2.0.2, with PowerPC and 68K code.
  14.  
  15. More REALbasic examples can be found on my Web Site at
  16.  
  17.   <http://www.tempel.org/rb/>
  18.  
  19. Enjoy!
  20.  
  21.  
  22. Overview
  23.  
  24. This Plugin implements a new Class for handling Mac OS Alias Records.
  25.  
  26. AliasRecords are like FolderItems, but can be made persistent: You can convert a FolderItem into a AliasRecord and store that AliasRecord in a file (like your Preferences file). Later you can retrieve that information again and convert it back into a FolderItem.
  27.  
  28. AliasRecords also appear inside Alias Files, that are usually created by the Finder. The enclosed sample application (Alias Mgr Plugin Demo.π) shows how to create and resolve such Alias Files.
  29.  
  30.  
  31. Installation
  32.  
  33. 1. Quit REALbasic if it is running
  34.  
  35. 2. Place the file TT's Alias Mgr Plugin into a folder called Plugins, which resides in the same folder where your REALbasic application is. If you want to run the enclosed demos, you might also need to copy some more Plugins, which are inside the Demos folder (all those plugins are also available from my web site, complete with source code and documentation).
  36.  
  37. 3. Now you can launch REALbasic again. The methods, controls or classes described below will be available to your RB applications and to the RB demo projects that came with this plugin.
  38.  
  39.  
  40. Plugin Description
  41.  
  42. The plugin provides a single Class:
  43.  
  44. MacAliasRecord Class
  45.  
  46.     Super Class
  47.  
  48.         Object
  49.  
  50.     Methods
  51.  
  52.         • Create(relPath as FolderItem, target as FolderItem) as Integer
  53.  
  54.             Creates an AliasRecord for a given file or folder. Returns zero if successful, otherwise a negative Mac OS error code.
  55.  
  56.         • Update(relPath as FolderItem, target as FolderItem) as Integer
  57.  
  58.             Updates an already created AliasRecord. Returns either a negative Mac OS error code, zero if the update didn't actually change the AliasRecord, or one if the record was changed (in this case you might want to update your record of the alias if you had stored it in a file).
  59.  
  60.         • GetRecord() as String
  61.  
  62.             Returns the AliasRecord in a String so that you can store it in a file, and pass it SetRecord for re-creating the AliasRecord (this string might contain any byte values, including zeros, so you can not display it or store it in a text file - you have to store it in a binary file or in a resource, instead!).
  63.  
  64.             Attention: The length of the String is not fixed! When the Alias changes, its length usually changes, too. If you want to save this string into a binary file, you must also save its current length so that you know how much bytes to retrieve if you read it back from the file later. An easier way to store Aliases in a file is by using the Resource Manager. The sample code "FolderItems in Preferences.rbp" shows how to accomplish this.
  65.  
  66.         • SetRecord(record as String)
  67.  
  68.             Use this method to revive an AliasRecord with the string you inquired from GetRecord earlier.
  69.  
  70.         • Resolve(relPath as FolderItem, mode as Integer) as FolderItem
  71.  
  72.             Converts an AliasRecord back into a FolderItem. For values to the mode parameter see the Properties below or pass in 0 for default searching (will not attempt to mount unavailable volumes).
  73.  
  74.             After calling this method, the property needsUpdate tells you whether the target has been renamed or moved, which suggests that you call Update in order to reflect the change in the AliasRecord. See the demo "FolderItems in Preferences.rbp" for an example.
  75.  
  76.         • GetInfo(idx as Integer) as String
  77.  
  78.             Returns information about the AliasRecord, without resolving it (no disk access will happen). Possible values for "idx":
  79.                 • -3: returns the Network Zone Name, if any.
  80.                 • -2: returns the Network Server Name, if any.
  81.                 • -1: returns the Volume Name.
  82.                 • 0: returns the Item Name.
  83.                 • 1 and higher: returns the parent directories of the item.
  84.  
  85.     Properties
  86.  
  87.         Arguments for the mode parameter of the Resolve method (they are actually like constants, since they are read-only and do not change at runtime). They may be added up to combine them:
  88.  
  89.         • attemptMount as Integer - attempts to mount a volume when it is not available (like network volumes and removable disks).
  90.         • noDialogs as Integer - suppresses any user interaction, like network login dialogs and disk insertion prompts. Only relevant if attemptMount is used.
  91.         • relFirst as Integer - if a relative path is given, this argument lets Resolve do a relative search before a absolute search. Without this argument, a relative search is only performed if the target is not found at its orginal absolute position.
  92.  
  93.         • needsUpdate as Boolean - after having called Resolve successfullly, this property indicates whether the AliasRecord is still up to date:
  94.                 true: the target of the Alias is still at the same location where it was last seen.
  95.                 false: the target has been moved or renamed. The Update method should be invoked.
  96.  
  97.         • version as Integer - returns a version number of the plugin (version 1.0 of this plugin returns 256 (or &H0100)).
  98.  
  99.  
  100. Examples
  101.  
  102.     Store the reference to a FolderItem in a Binary File
  103.  
  104.         Dim alias as MacAliasRecord, f as FolderItem
  105.         Dim bf as BinaryStream, s as String
  106.         f = ... // the FolderItem you want to save
  107.         bf = ... // open your binary file here
  108.         alias = new MacAliasRecord
  109.         if alias.Create(nil, f) = 0 then
  110.             s = alias.GetRecord()
  111.             bf.WriteLong LenB(s)    // this saves the length of the record
  112.             bf.Write s                                            // this saves the record itself
  113.         end
  114.  
  115.     Retrieve the reference to a FolderItem from a Binary File
  116.  
  117.         Dim alias as MacAliasRecord, f as FolderItem
  118.         Dim bf as BinaryStream, l as Integer
  119.         bf = ... // open your binary file here
  120.         alias = new MacAliasRecord
  121.         l = bf.ReadLong
  122.         alias.SetRecord bf.Read(l)
  123.         f = alias.Resolve(nil, alias.attemptMount)
  124.         if alias.needsUpdate then
  125.             if alias.Update(nil, f) = 1 then
  126.                 ... you might want to save the updated alias in your file here
  127.             end
  128.         end
  129.         // f now describes the FolderItem again.
  130.         // It may not be existing any more, however, so here's a check for that:
  131.         if not f.exists then
  132.             msgBox "oops! the file is not available any more. Select a new one, please"
  133.             ... let the user locate the file
  134.         end
  135.  
  136.  
  137. Plugin Programming Information
  138.  
  139. The plugin code is a Metrowerks CodeWarrior Pro 3 (IDE 3.1) project.
  140. If you have an older CW version that refuses to open the prj file, then create a new and set/enable the following prj options:
  141. • create 68K target (set to 68K linker)
  142. • prj type: Code Resource, File Name "CatalogSearch-Plugin", Creator "SfTg", Type "RBPl", ResType "PL68", ResID "128", Extended Resource, Header Type "Standard"
  143. • C/C++ language settings: Prefix File "MacHeaders.h"
  144. • 68K Processor: 68020 Codegen, Code Model "Smart", Struct Alignm. "PowerPC", 4-Byte Ints, 8-Byte Doubles, MPW C Call. Conv.
  145. • 68K Linker: Link Single Segment, Merge Compiler Glue…, Dead-strip Static Init Code
  146. • Add the files "Plugin Source.cpp", "PluginMain.cpp", "MacOS.lib", "Version Info.rsrc" and a 68K C lib with (4i_8d) in its name to the project.
  147.  
  148. To compile the project, you also need to have the "Plugin SDK" available, which you can download from RB's website.
  149.  
  150.  
  151. Revision history
  152.  
  153. 3 July 1999, v1.0:
  154.     First release.
  155.  
  156. 4 July 1999:
  157.     Documentation changes.
  158.  
  159. 5 July 1999, v1.1:
  160.     Added "needsUpdate" property, added store/retrieve examples in this doc, finished a second sample project.
  161.